home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Technology Seed / Jan. '98 ATS.toast / QuickTime™ 3.0b11 / QTPublicInterfaces / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-01-12  |  13.3 KB  |  487 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    QuickTime 3.0 Beta
  8.  
  9.      Copyright:    © 1993-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __NAMEREGISTRY__
  19. #define __NAMEREGISTRY__
  20.  
  21. #ifndef __MACTYPES__
  22. #include <MacTypes.h>
  23. #endif
  24.  
  25.  
  26.  
  27. #if PRAGMA_ONCE
  28. #pragma once
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_STRUCT_ALIGN
  40.     #pragma options align=power
  41. #elif PRAGMA_STRUCT_PACKPUSH
  42.     #pragma pack(push, 2)
  43. #elif PRAGMA_STRUCT_PACK
  44.     #pragma pack(2)
  45. #endif
  46.  
  47. /*******************************************************************************
  48.  * 
  49.  * Foundation Types
  50.  *
  51.  */
  52. /* Value of a property */
  53. typedef void *                            RegPropertyValue;
  54. /* Length of property value */
  55. typedef UInt32                             RegPropertyValueSize;
  56. /*******************************************************************************
  57.  * 
  58.  * RegEntryID    :    The Global x-Namespace Entry Identifier
  59.  *
  60.  */
  61.  
  62. struct RegEntryID {
  63.     UInt32                             contents[4];
  64. };
  65. typedef struct RegEntryID                RegEntryID;
  66. typedef RegEntryID *                    RegEntryIDPtr;
  67. /*******************************************************************************
  68.  *
  69.  * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  70.  *
  71.  *    • Names are a colon-separated list of name components.  Name components
  72.  *      may not themselves contain colons.  
  73.  *    • Names are presented as null-terminated ASCII character strings.
  74.  *    • Names follow similar parsing rules to Apple file system absolute
  75.  *      and relative paths.  However the '::' parent directory syntax is
  76.  *      not currently supported.
  77.  */
  78. /* Max length of Entry Name */
  79.  
  80. enum {
  81.     kRegCStrMaxEntryNameLength    = 47
  82. };
  83.  
  84. /* Entry Names are single byte ASCII */
  85.  
  86. typedef char                             RegCStrEntryName;
  87. typedef char *                            RegCStrEntryNamePtr;
  88. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  89. typedef char                             RegCStrEntryNameBuf[48];
  90. typedef char                             RegCStrPathName;
  91. typedef UInt32                             RegPathNameSize;
  92.  
  93. enum {
  94.     kRegPathNameSeparator        = ':',                            /* 0x3A */
  95.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  96.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  97. };
  98.  
  99. /*******************************************************************************
  100.  *
  101.  * Property Name and ID Definitions
  102.  *    (Applies to all Properties Regardless of NameSpace)
  103.  */
  104.  
  105. enum {
  106.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  107.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  108. };
  109.  
  110. typedef char                             RegPropertyNameBuf[32];
  111. typedef char                             RegPropertyName;
  112. typedef char *                            RegPropertyNamePtr;
  113. /*******************************************************************************
  114.  *
  115.  * Iteration Operations
  116.  *
  117.  *    These specify direction when traversing the name relationships
  118.  */
  119. typedef UInt32                             RegIterationOp;
  120. typedef RegIterationOp                     RegEntryIterationOp;
  121.  
  122. enum {
  123.                                                                 /* Absolute locations*/
  124.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  125.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  126.                                                                 /* "Downward" Relationships*/
  127.     kRegIterChildren            = 0x00000004,                    /* include all children */
  128.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  129.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  130.                                                                 /* "Horizontal" Relationships    */
  131.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  132.                                                                 /* Keep doing the same thing*/
  133.     kRegIterContinue            = 0x00000001
  134. };
  135.  
  136. /*******************************************************************************
  137.  *
  138.  * Name Entry and Property Modifiers
  139.  *
  140.  *
  141.  *
  142.  * Modifiers describe special characteristics of names
  143.  * and properties.  Modifiers might be supported for
  144.  * some names and not others.
  145.  * 
  146.  * Device Drivers should not rely on functionality
  147.  * specified as a modifier.
  148.  */
  149. typedef UInt32                             RegModifiers;
  150. typedef RegModifiers                     RegEntryModifiers;
  151. typedef RegModifiers                     RegPropertyModifiers;
  152.  
  153. enum {
  154.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  155.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  156.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  157.     kRegModifierMask            = (long)0xFF000000                /* mods to just this entry */
  158. };
  159.  
  160. /* Universal Property Modifiers */
  161.  
  162. enum {
  163.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  164.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  165. };
  166.  
  167. /* ///////////////////////
  168. //
  169. // The Registry API
  170. //
  171. /////////////////////// */
  172. /* ///////////////////////
  173. //
  174. // Entry Management
  175. //
  176. /////////////////////// */
  177.  
  178. /*-------------------------------
  179.  * EntryID handling
  180.  */
  181. /*
  182.  * Initialize an EntryID to a known invalid state
  183.  *   note: invalid != uninitialized
  184.  */
  185. EXTERN_API_C( OSStatus )
  186. RegistryEntryIDInit                (RegEntryID *            id);
  187.  
  188. /*
  189.  * Compare EntryID's for equality or if invalid
  190.  *
  191.  * If a NULL value is given for either id1 or id2, the other id 
  192.  * is compared with an invalid ID.  If both are NULL, the id's 
  193.  * are consided equal (result = true). 
  194.  */
  195. EXTERN_API_C( Boolean )
  196. RegistryEntryIDCompare            (const RegEntryID *        id1,
  197.                                  const RegEntryID *        id2);
  198.  
  199. /*
  200.  * Copy an EntryID
  201.  */
  202. EXTERN_API_C( OSStatus )
  203. RegistryEntryIDCopy                (const RegEntryID *        src,
  204.                                  RegEntryID *            dst);
  205.  
  206. /*
  207.  * Free an ID so it can be reused.
  208.  */
  209. EXTERN_API_C( OSStatus )
  210. RegistryEntryIDDispose            (RegEntryID *            id);
  211.  
  212. /*-------------------------------
  213.  * Adding and removing entries
  214.  *
  215.  * If (parentEntry) is NULL, the name is assumed
  216.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  217.  */
  218. EXTERN_API_C( OSStatus )
  219. RegistryCStrEntryCreate            (const RegEntryID *        parentEntry,
  220.                                  const RegCStrPathName * name,
  221.                                  RegEntryID *            newEntry);
  222.  
  223. EXTERN_API_C( OSStatus )
  224. RegistryEntryDelete                (const RegEntryID *        id);
  225.  
  226. /*---------------------------
  227.  * Traversing the namespace
  228.  *
  229.  * To support arbitrary namespace implementations in the future,
  230.  * I have hidden the form that the place pointer takes.  The previous
  231.  * interface exposed the place pointer by specifying it as a
  232.  * RegEntryID.
  233.  *
  234.  * I have also removed any notion of returning the entries
  235.  * in a particular order, because an implementation might
  236.  * return the names in semi-random order.  Many name service
  237.  * implementations will store the names in a hashed lookup
  238.  * table.
  239.  *
  240.  * Writing code to traverse some set of names consists of
  241.  * a call to begin the iteration, the iteration loop, and
  242.  * a call to end the iteration.  The begin call initializes
  243.  * the iteration cookie data structure.  The call to end the 
  244.  * iteration should be called even in the case of error so 
  245.  * that allocated data structures can be freed.
  246.  *
  247.  *    Create(...)
  248.  *    do {
  249.  *        Iterate(...);
  250.  *    } while (!done);
  251.  *    Dispose(...);
  252.  *
  253.  * This is the basic code structure for callers of the iteration
  254.  * interface.
  255.  */
  256.  
  257. typedef struct OpaqueRegEntryIter*         RegEntryIter;
  258. /* 
  259.  * create/dispose the iterator structure
  260.  *   defaults to root with relationship = kRegIterDescendants
  261.  */
  262. EXTERN_API_C( OSStatus )
  263. RegistryEntryIterateCreate        (RegEntryIter *            cookie);
  264.  
  265. EXTERN_API_C( OSStatus )
  266. RegistryEntryIterateDispose        (RegEntryIter *            cookie);
  267.  
  268. /* 
  269.  * set Entry Iterator to specified entry
  270.  */
  271. EXTERN_API_C( OSStatus )
  272. RegistryEntryIterateSet            (RegEntryIter *            cookie,
  273.                                  const RegEntryID *        startEntryID);
  274.  
  275. /*
  276.  * Return each value of the iteration
  277.  *
  278.  * return entries related to the current entry
  279.  * with the specified relationship
  280.  */
  281. EXTERN_API_C( OSStatus )
  282. RegistryEntryIterate            (RegEntryIter *            cookie,
  283.                                  RegEntryIterationOp     relationship,
  284.                                  RegEntryID *            foundEntry,
  285.                                  Boolean *                done);
  286.  
  287. /*
  288.  * return entries with the specified property
  289.  *
  290.  * A NULL RegPropertyValue pointer will return an
  291.  * entry with the property containing any value.
  292.  */
  293. EXTERN_API_C( OSStatus )
  294. RegistryEntrySearch                (RegEntryIter *            cookie,
  295.                                  RegEntryIterationOp     relationship,
  296.                                  RegEntryID *            foundEntry,
  297.                                  Boolean *                done,
  298.                                  const RegPropertyName * propertyName,
  299.                                  const void *            propertyValue,
  300.                                  RegPropertyValueSize     propertySize);
  301.  
  302. /*--------------------------------
  303.  * Find a name in the namespace
  304.  *
  305.  * This is the fast lookup mechanism.
  306.  * NOTE:  A reverse lookup mechanism
  307.  *      has not been provided because
  308.  *        some name services may not
  309.  *        provide a fast, general reverse
  310.  *        lookup.
  311.  */
  312. EXTERN_API_C( OSStatus )
  313. RegistryCStrEntryLookup            (const RegEntryID *        searchPointID,
  314.                                  const RegCStrPathName * pathName,
  315.                                  RegEntryID *            foundEntry);
  316.  
  317. /*---------------------------------------------
  318.  * Convert an entry to a rooted name string
  319.  *
  320.  * A utility routine to turn an Entry ID
  321.  * back into a name string.
  322.  */
  323. EXTERN_API_C( OSStatus )
  324. RegistryEntryToPathSize            (const RegEntryID *        entryID,
  325.                                  RegPathNameSize *        pathSize);
  326.  
  327. EXTERN_API_C( OSStatus )
  328. RegistryCStrEntryToPath            (const RegEntryID *        entryID,
  329.                                  RegCStrPathName *        pathName,
  330.                                  RegPathNameSize         pathSize);
  331.  
  332. /*
  333.  * Parse a path name.
  334.  *
  335.  * Retrieve the last component of the path, and
  336.  * return a spec for the parent.
  337.  */
  338. EXTERN_API_C( OSStatus )
  339. RegistryCStrEntryToName            (const RegEntryID *        entryID,
  340.                                  RegEntryID *            parentEntry,
  341.                                  RegCStrEntryName *        nameComponent,
  342.                                  Boolean *                done);
  343.  
  344. /* //////////////////////////////////////////////////////
  345. //
  346. // Property Management
  347. //
  348. ////////////////////////////////////////////////////// */
  349. /*-------------------------------
  350.  * Adding and removing properties
  351.  */
  352. EXTERN_API_C( OSStatus )
  353. RegistryPropertyCreate            (const RegEntryID *        entryID,
  354.                                  const RegPropertyName * propertyName,
  355.                                  const void *            propertyValue,
  356.                                  RegPropertyValueSize     propertySize);
  357.  
  358. EXTERN_API_C( OSStatus )
  359. RegistryPropertyDelete            (const RegEntryID *        entryID,
  360.                                  const RegPropertyName * propertyName);
  361.  
  362. /*---------------------------
  363.  * Traversing the Properties of a name
  364.  *
  365.  */
  366. typedef struct OpaqueRegPropertyIter*     RegPropertyIter;
  367. EXTERN_API_C( OSStatus )
  368. RegistryPropertyIterateCreate    (const RegEntryID *        entry,
  369.                                  RegPropertyIter *        cookie);
  370.  
  371. EXTERN_API_C( OSStatus )
  372. RegistryPropertyIterateDispose    (RegPropertyIter *        cookie);
  373.  
  374. EXTERN_API_C( OSStatus )
  375. RegistryPropertyIterate            (RegPropertyIter *        cookie,
  376.                                  RegPropertyName *        foundProperty,
  377.                                  Boolean *                done);
  378.  
  379. /*
  380.  * Get the value of the specified property for the specified entry.
  381.  *
  382.  */
  383. EXTERN_API_C( OSStatus )
  384. RegistryPropertyGetSize            (const RegEntryID *        entryID,
  385.                                  const RegPropertyName * propertyName,
  386.                                  RegPropertyValueSize *    propertySize);
  387.  
  388. /*
  389.  * (*propertySize) is the maximum size of the value returned in the buffer
  390.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  391.  * value returned.
  392.  */
  393. EXTERN_API_C( OSStatus )
  394. RegistryPropertyGet                (const RegEntryID *        entryID,
  395.                                  const RegPropertyName * propertyName,
  396.                                  void *                    propertyValue,
  397.                                  RegPropertyValueSize *    propertySize);
  398.  
  399. EXTERN_API_C( OSStatus )
  400. RegistryPropertySet                (const RegEntryID *        entryID,
  401.                                  const RegPropertyName * propertyName,
  402.                                  const void *            propertyValue,
  403.                                  RegPropertyValueSize     propertySize);
  404.  
  405. /* //////////////////////////////////////////////////////
  406. //
  407. // Modibute (err, I mean Modifier) Management
  408. //
  409. ////////////////////////////////////////////////////// */
  410. /*
  411.  * Modifiers describe special characteristics of names
  412.  * and properties.  Modifiers might be supported for
  413.  * some names and not others.
  414.  * 
  415.  * Device Drivers should not rely on functionality
  416.  * specified as a modifier.  These interfaces
  417.  * are for use in writing Experts.
  418.  */
  419. /*
  420.  * Get and Set operators for entry modifiers
  421.  */
  422. EXTERN_API_C( OSStatus )
  423. RegistryEntryGetMod                (const RegEntryID *        entry,
  424.                                  RegEntryModifiers *    modifiers);
  425.  
  426. EXTERN_API_C( OSStatus )
  427. RegistryEntrySetMod                (const RegEntryID *        entry,
  428.                                  RegEntryModifiers         modifiers);
  429.  
  430. /*
  431.  * Get and Set operators for property modifiers
  432.  */
  433. EXTERN_API_C( OSStatus )
  434. RegistryPropertyGetMod            (const RegEntryID *        entry,
  435.                                  const RegPropertyName * name,
  436.                                  RegPropertyModifiers *    modifiers);
  437.  
  438. EXTERN_API_C( OSStatus )
  439. RegistryPropertySetMod            (const RegEntryID *        entry,
  440.                                  const RegPropertyName * name,
  441.                                  RegPropertyModifiers     modifiers);
  442.  
  443. /*
  444.  * Iterator operator for entry modifier search
  445.  */
  446. EXTERN_API_C( OSStatus )
  447. RegistryEntryMod                (RegEntryIter *            cookie,
  448.                                  RegEntryIterationOp     relationship,
  449.                                  RegEntryID *            foundEntry,
  450.                                  Boolean *                done,
  451.                                  RegEntryModifiers         matchingModifiers);
  452.  
  453. /*
  454.  * Iterator operator for entries with matching 
  455.  * property modifiers
  456.  */
  457. EXTERN_API_C( OSStatus )
  458. RegistryEntryPropertyMod        (RegEntryIter *            cookie,
  459.                                  RegEntryIterationOp     relationship,
  460.                                  RegEntryID *            foundEntry,
  461.                                  Boolean *                done,
  462.                                  RegPropertyModifiers     matchingModifiers);
  463.  
  464.  
  465.  
  466.  
  467. #if PRAGMA_STRUCT_ALIGN
  468.     #pragma options align=reset
  469. #elif PRAGMA_STRUCT_PACKPUSH
  470.     #pragma pack(pop)
  471. #elif PRAGMA_STRUCT_PACK
  472.     #pragma pack()
  473. #endif
  474.  
  475. #ifdef PRAGMA_IMPORT_OFF
  476. #pragma import off
  477. #elif PRAGMA_IMPORT
  478. #pragma import reset
  479. #endif
  480.  
  481. #ifdef __cplusplus
  482. }
  483. #endif
  484.  
  485. #endif /* __NAMEREGISTRY__ */
  486.  
  487.